SETCOLOR & COLOR commands and SCREEN TABLE with GRAPHIC MODES
By lived.ch, 15:33 08.12.2024
BASIC:	  TURBO BASIC 1.5 XL
ASSEMBLY: Synapse-Assembler {unused so far}
---------------------------------------------------------------------------------------------------------------------



***************************************************************************************************

ATARI COLORS AND SCREEN GRAPHIC MODES ARE SOMEWHAT A VERY COMPLICATED MATTER!
IMPOSSIBLE TO EXPLAIN IT THE EASY WAY!

THEREFORE, READ THIS BOOK! IT'S COMTAINING ALL YOU NEED!:

	>>> "ATARI GRAPHICS & ARCADE GAME DESIGN" by Jeffrey Stanton & Daniel Pinal <<<

***************************************************************************************************



---------------------------------------------------------------------------------------------------------------------
****************************************************************************************
ATARI - COLOR TABLE : {16 BASE COLORS. The rest is then just different luminance value}*
****************************************************************************************



GOOD FOR: 	SETCOLOR, COLOR, POKE commands to access all registers in BASIC and Assembler 
NOTE : 		COLOR always follows the SETCOLOR {POKE} and is always one number higher than COLREG#
EXAMPLE:	SETCOLOR 0,4,10
	
--------------------------------------------------|------------------------------------------------------------------|
SETCOLOR COLREG#, COLOR#, LUMINANCE#  		  | POKE ADDRESSES TO ACCESS REG#, COLOR#, LUMINANCE#                |
--------------|---------- |----------|------------|-----------------------------------|--------------|---------------|
	      | COLREG#   | COLOR#   | LUMINANCE# | REGISTER ASSEMBLER/BASIC          | COLOR# & LUMINANCE# VALUES   |
Color 	      |	DEC/HEX   | DEC HEX  | DEC  HEX   | DEC/HEX    DEC/HEX                | DECIMAL      | HEXDECIMAL    |
--------------|-----------|----|-----|----|-------|----------|------------------------|--------------|---------------|
Black 	      |	 *{=704}  | 00 | $00 | 00 | $00   | 704,$2C0 | 53266,$D012,PMCOLOR0** | 000.....015  | $00.....$0F   |
Rust 	      |	 *{=705}  | 01 | $01 | 01 | $01   | 705,$2C0 | 53267,$D013,PMCOLOR1   | 016.....031  | $10.....$1F   |
Red-Orange    |	 *{=706}  | 02 | $02 | 02 | $02   | 706,$2C0 | 53268,$D014,PMCOLOR2   | 032.....047  | $20.....$2F   |
Dark-Orange   |	 *{=707}  | 03 | $03 | 03 | $03   | 707,$2C0 | 53269,$D015,PMCOLOR3   | 048.....063  | $30.....$3F   |
Red 	      |	0 {=708}  | 04 | $04 | 04 | $04   | 708,$2C0 | 53270,$D016,PLAYFIELD0 | 064.....079  | $40.....$4F   |
Dark-Lavender |	1 {=709}  | 05 | $05 | 05 | $05   | 709,$2C0 | 53271,$D017,PLAYFIELD1 | 080.....095  | $50.....$5F   |
Cobalt-Blue   |	2 {=710}  | 06 | $06 | 06 | $06   | 710,$2C0 | 53272,$D018,PLAYFIELD2 | 096.....111  | $60.....$6F   |
Ultramarine   |	3 {=711}  | 07 | $07 | 07 | $07   | 711,$2C0 | 53273,$D019,PLAYFIELD3 | 112.....127  | $70.....$7F   |
Medium blue   |	4 {=712}  | 08 | $08 | 08 | $08   | 712,$2C0 | 53274,$D01A,PLAYFIELD4 | 128.....143  | $80.....$8F   |
Dark blue     |-----------| 09 | $09 | 09 | $09   |-----------------------------------| 144.....159  | $90.....$9F   |
Blue-grey     |		  | 10 | $0A | 10 | $0A   | * =                	  	      | 160.....175  | $A0.....$AF   |
Olive green   |		  | 11 | $0B | 11 | $0B   | SHADOW Registers 704-707 are      | 176.....191  | $B0.....$BF   |
Medium green  |		  | 12 | $0C | 12 | $0C   | accessible only via POKE in BASIC | 192.....207  | $C0.....$CF   |
Dark green    |	 	  | 13 | $0D | 13 | $0D   | and not by using SETCOLOR command!| 208.....223  | $D0.....$DF   |
Orange-green  |		  | 14 | $0E | 14 | $0E   | And 708-712 also with SETCOLOR.   | 224.....239  | $E0.....$EF   |
Orange 	      |		  | 15 | $0F | 15 | $0F   | ** = Real REG# with POKE only.    | 240.....255  | $F0.....$FF   |
--------------|---------- |----|-----|----|-------|-----------------------------------|--------------|---------------|     
										      |	Color# min. <Luminance> max. |
										      | 000......................015 |
By lived.ch, 13:58 12.12.2024         						      | 016 < next Color# etc.       |
--------------------------------------------------------------------------------------|------------------------------|



---------------------------------------------------------------------------------------------------------------------
*********************************************************
HOW TO USE COLOR REGISTER DEPENDING ON THE GRAPHIC MODE:*
*********************************************************



The usage of COLREG# - COLOR# - LUMINANCE# is dependent on used GRAPHICS MODE.
Find here a short table of what is where active/inactive:

ATARI GRAPHIC MODES {COLOR REGISTER USAGE}: SETCOLOR or POKE
-----------------------------|-|---------------------------------------------------------------------------------|
			     | | ATARI-800XL : COLOR#, REGISTERS# AND MEMORY ADDRESSES# 			 |
			     | |-----------------------------------||--------------------------------------------| 
			     | |>Accessible ONLY with POKE command<||>Accessible with POKE and SETCOLOR command <|
----			     | |PMCOLOR0|PMCOLOR1|PMCOLOR2|PMCOLOR3||PLFIELD0|PLFIELD1|PLFIELD2|PLFIELD3|PLFIELD4|
# COLORS |   GRAPHIC MODES   | | 00/704 | 01/705 | 02/706 | 03/707 || 00/708 | 01/709 | 02/710 | 03/711 | 04/712 |
---------|----|----|----|----| |--------|--------|--------|--------||--------|--------|--------|--------|--------|
4	 | 03 | 05 | 07 | 15 |>|   	|   	 |   	  |        ||   xx   |   xx   |   xx   |        |   xx   |
---------|----|----|----|----| |--------|--------|--------|--------||--------|--------|--------|--------|--------|
2	 | 04 | 06 | 14 |    |>|   	|	 |	  |	   ||   xx   |	      |	       |	|   xx	 | 
---------|----|----|----|----| |--------|--------|--------|--------||--------|--------|--------|--------|--------|
1	 | 08 |    |    |    |>|	|	 |        |        ||	     | xx LUM |   xx   |        |        |
---------|----|----|----|----| |--------|--------|--------|--------||--------|--------|--------|--------|--------|
16-SHADES| 9* |    |    |    |>|	|	 |        |        ||        |        |        |        |   xx   |
---------|----|----|----|----| |--------|--------|--------|--------||--------|--------|--------|--------|--------|
9	 | 10*|    |    |    |>| xx PF  |   xx   |   xx   |   xx   ||   xx   |   xx   |   xx   |   xx   |   xx   |
---------|----|----|----|----| |--------|--------|--------|--------||--------|--------|--------|--------|--------|
16- 1xLUM| 11*|    |    |    |>|        |        |        |        ||        |        |        |        |   xx   |
---------|----|----|----|----| |--------|--------|--------|--------||--------|--------|--------|--------|--------|
4- MCOLOR| 12 | 13 |    |    |>|MULTICOLOR* requires custom defined||   xx   |   xx   |   xx   |   xx   |   xx   |
---------|----|----|----|----|>|MC Characters set made with color  ||   01   |   10   |   11   |   11   |   00   |
			     |>|pattern as seen on the right side. ||        |        | NORMAL | REVERSE|        |
-----------------------------|-|-----------------------------------||--------|--------|--------|--------|--------|
*   = Sprite collision registers are disabled!
PF  = PLAYFIELD {Note: PLAYFIELD and BACKGROUND {border} are the same color in GRAPHICS 10}
LUM = Luminance



---------------------------------------------------------------------------------------------------------------------
*************************************
ATARI-800XL AVAILABLE GRAPHIC MODES:*
*************************************



GRAPHIC MODES can be used as a single mode or be a mix of a different graphic modes.
You can achieve that by using DisplayList {DL} and DislayListInterrupt {DLI}
Further below you'll find some examples of how to do it.

It is also important to know that the start address of the screen isn't the same and
depends on the used GRAPHIC MODE {initial one}

This is how you can find the start address of *DisplayList : 
{First address is LowByte and the second is HighByte

 DListI = PEEK(512)+256*PEEK(513)	= Display List Interrupt Vector (VDSLST)

 POKE 559,34	  {default value}	= DMA Control Register (SDMCTL)

*DListA = PEEK(560)+256*PEEK(561)	= Display List Address (SDLSTL)

 POKE 54286, xx ($D40E) 		= Non-maskable Interrupt Enable (NMIEN)
					= 64 	($40) - upon powerup to enable VBI's
					= 128 	($80) - enables DLI's
					= 192 	($CO) - enables both
					- 0 	($00) - zero disables both.

|---------------|-------|------|-------|----------------|-------|---------|
|GRAPHICS MODE  |NUMBER |ANTIC |COLOR  |RESOLUTION	|SCNLINE|MEM BYTES|
|---------------|-------|------|-------|----------------|-------|---------|
|Text Screen	|0	|2     |1,2Lum |40X x 24Y   CHR |8   	|992	  |
|---------------|-------|------|-------|----------------|-------|---------|
|Text Screen	|17	|      |5      |20X x 24Y   CHR |8      |672      |
|with different |1-wTxt	|6     |5      |20X x 20Y   CHR |8      |674	  |
|X & Y sized	|-------|------|-------|----------------|-------|---------|
|Characters	|18	|      |5      |20X x 12Y   CHR |16     |420      |
|4 Modes total	|2-wTxt	|7     |5      |20X x 10Y   CHR |16	|424	  |
|---------------|-------|------|-------|----------------|-------|---------|
|Graphics 	|19	|      |4      |40X x 24Y   PIX |8      |432	  |
|Screen Modes	|3-wTxt	|8     |4      |40X x 20Y   PIX |8	|434	  |
|4-Colors max.  |-------|------|-------|----------------|-------|---------|
|Independent of	|21	|      |4      |80X x 48Y   PIX |4      |1176	  |
|the possible	|5-wTxt |A     |4      |80X x 40Y   PIX |4	|1174	  |
|resolution.	|-------|------|-------|----------------|-------|---------|
|		|23	|      |4      |160X x 96Y  PIX |2      |4200	  |
|		|7-wTxt	|D     |4      |160X x 80Y  PIX |2	|4190	  |
|		|-------|------|-------|----------------|-------|---------|
|		|31	|      |4      |160X x 192Y PIX |2      |8138     |
|		|15-wTxt|E     |4      |160X x 160Y PIX |2      |8112     |
|---------------|-------|------|-------|----------------|-------|---------|
|Graphics	|20	|      |2      |80X x 48Y   PIX |4      |696      |
|Screen Modes	|4-wTxt |9     |2      |80X x 40Y   PIX |4      |694      |
|2-Colors max.  |-------|------|-------|----------------|-------|---------|
|Independent of	|22	|      |2      |160X x 96Y  PIX |2      |2184     |
|the possible 	|6-wTxt	|B     |2      |160X x 80Y  PIX |2      |2174     |
|resolution.	|-------|------|-------|----------------|-------|---------|
|		|30	|      |2      |160X x 192Y PIX |2      |4296     |
|		|14-wTxt|C     |2      |160X x 160Y PIX |2      |4270     |
|---------------|-------|------|-------|----------------|-------|---------|
|High resolution|24	|      |1,2Lum |320X x 192  PIX |1      |8138     |
|Graphics Mode	|8-wTxt	|F     |1,2Lum |320X x 160  PIX |1      |8112     |
|---------------|-------|------|-------|----------------|-------|---------|
|GTIA-MODES     |       |      |       |                |       |         |
|{POKE 623,64}  |9	|F     |1,16Lum|80X x 192   PIX |1	|8138	  |
|{POKE 623,128}	|10	|F     |9      |80X x 192   PIX |1	|8138	  |
|{POKE 623,192}	|11	|F     |16     |80X x 192   PIX |1	|8138	  | 
|---------------|-------|------|-------|----------------|-------|---------|
|Text Screen	|28	|      |4      |40X x 24    CHR |8      |1152     |
|with different	|12-wTxt|4     |4      |40X x 20    CHR |8      |1154     |
|X & Y sized	|-------|------|-------|----------------|-------|---------|
|Characters	|29	|      |4      |40X x 12    CHR |16     |660      |
|4-Colors max.	|13-wTxt|5     |4      |40X x 10    CHR |16     |664      |
|---------------|-------|------|-------|----------------|-------|---------|


And now here some examples:

---------------------------------------------------------------------------------------------------------------------
LISTING 1
---------------------------------------------------------------------------------------------------------------------

MULTICOLOR 1: GRAPHICS MODE 12+16 {NO TEXT LINES AT THE BOTTOM}

LIST

10 POKE 82,1:GRAPHICS 12+16
15 TEXT 0,0,"ATARI":B=1
20 TEXT 0,10,"800XL"
25 SETCOLOR 4,0,0:COLOR 0
30 A=A+B
35 IF A>15 THEN A=15:B=-1
40 IF A<0 THEN A=0:B=ABS(B)
45 FOR C=0 TO 38:NEXT C
50 SETCOLOR 0,1,A:COLOR 1
55 SETCOLOR 1,1,A:COLOR 2
60 SETCOLOR 2,1,A:COLOR 3
65 GOTO 30

READY


---------------------------------------------------------------------------------------------------------------------
LISTING 2
---------------------------------------------------------------------------------------------------------------------

MULTICOLOR 2: GRAPHICS MODE 12+16 {NO TEXT LINES AT THE BOTTOM}



LIST

10 POKE 82,1:GRAPHICS 12+16
15 TEXT 0,0,"ATARI":B=1
20 TEXT 0,10,"800XL"
25 SETCOLOR 4,0,0:COLOR 0
30 A=A+B
35 IF A>15 THEN A=15:B=-1:M=RND(1)*15
40 IF A<0 THEN A=0:B=ABS(B)
45 FOR C=0 TO 50:NEXT C
50 SETCOLOR 0,3,M:COLOR 1
55 SETCOLOR 1,1,M:COLOR 2
60 SETCOLOR 2,7,A:COLOR 3
65 GOTO 30

READY


---------------------------------------------------------------------------------------------------------------------
LISTING 3
---------------------------------------------------------------------------------------------------------------------

MULTICOLOR 2: GRAPHICS MODE 3+16 {NO TEXT LINES AT THE BOTTOM}

LIST

10 POKE 82,1:GRAPHICS 3+16
25 SETCOLOR 4,0,0:COLOR 0
55 SETCOLOR 0,2,5:COLOR 1
57 CIRCLE 20,20,3,3
60 SETCOLOR 1,3,8:COLOR 2
63 TEXT 0,0,"ATARI"
64 CIRCLE 20,20,1,1
65 SETCOLOR 2,11,8:COLOR 3
70 CIRCLE 20,20,2,2
71 CIRCLE 20,20,5,5
75 TEXT 0,7,"800XL"
80 GOTO 65

READY




GTIA EXAMPLES >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
---------------------------------------------------------------------------------------------------------------------
LISTING 1
---------------------------------------------------------------------------------------------------------------------

GRAPHICS MODE 10:

	- 9 COLORS are used
	- POKE 704,x is the PLAYFIELD AND BACKGROUND {border} COLOR
	- OTHER REGISTERS UNTIL 712 ARE REGULAR COLOR REGISTERS 
	- Collision register aren't working here {not in all 3 GTIA modes}
	- Sprite {Player/Missile color registers are used}
	  It means that Players/Missile won't be visible on the area with the same color.

You'll notice how color of the text is changing even if it isn't part of the loop.


LIST

10 POKE 82,1:GRAPHICS 10
13 POKE 704,0:REM PLAYFIELD/BG COLOR
15 Z=192/2:K=10:DIM A$(11)
16 A$="GFX    M10":TEXT 0,0,A$
19 FOR Y=0 TO 255 STEP 16
22   FOR X=0 TO 8
25     POKE 705+X,(Y+X)
28     COLOR X
31     CIRCLE 40,Z,K+(X),K+(X*6)
34   NEXT X
37 NEXT Y
40 GOTO 40

READY


---------------------------------------------------------------------------------------------------------------------
LISTING 2
---------------------------------------------------------------------------------------------------------------------

GRAPHICS MODE 9:

	- 16 COLORS are used, but ONLY as a gradient {shades of one base color}
	- The main color register is COLOR4 {= SETCOLOR 4,2,0}
	  or POKE 712,xx {see color table for BASE COLORS} and COLOR # is shades 0-15
	- OTHER REGISTERS UNTIL 712 ARE REGULAR COLOR REGISTERS 
	- Collision register aren't working here {not in all 3 GTIA modes}
	- All other color registers are not used

You'll notice how color of the text is changing even if it isn't part of the loop.


LIST

10 POKE 82,1:GRAPHICS 9
13 POKE 708,0:REM PLAYFIELD/BG COLOR
15 Z=192/2:K=10:DIM A$(11)
16 A$="GFX    M09":TEXT 0,0,A$
19 FOR Y=0 TO 255 STEP 16
22   FOR X=0 TO 15
25     POKE 712,Y
28     COLOR X
31     CIRCLE 40,Z,K+(X),K+(X*6)
34   NEXT X
37 NEXT Y
40 GOTO 40

READY


---------------------------------------------------------------------------------------------------------------------
LISTING 3
---------------------------------------------------------------------------------------------------------------------

GRAPHICS MODE 11:

	- 16 COLORS are used, with ONLY ONE luminance value over the channel 4 {712}
	- Colors itself are addressed over COLOR {or POKE, see COLOR table}
	- Collision register aren't working here {not in all 3 GTIA modes}
	- All other color registers are not used

You'll notice how color of the text is changing even if it isn't part of the loop.


LIST

10 POKE 82,1:GRAPHICS 11
12 Z=192/2:K=10:DIM A$(11)
14 A$="GFX    M11":TEXT 0,0,A$
16 FOR Y=0 TO 10
18   FOR X=0 TO 15
20     POKE 712,X
22     COLOR X
24     CIRCLE 40,Z,K+(X),K+(X*6)
26   NEXT X
28   FOR P=0 TO 250:NEXT P
30 NEXT Y
32 GOTO 32

READY


---------------------------------------------------------------------------------------------------------------------
WHY ATARI IS SLOWER IN MANY OCCASIONS COMPARED TO 1MHz CPU competition!?
---------------------------------------------------------------------------------------------------------------------

In case you wonder {from the book Atari Graphics and Arcade Game Design}
why Atari architecture needed faster CPU to not fall behind those with 1MHz CPU:


"There is one more important point for those readers who still need to count cycles":

Although a horizontal line takes 63.5 microseconds, you do not have 113 cycles per
line (63.5 x 1.79 = 113.6).  This is because ANTIC's Direct Memory Access (DMA) ability
allows it to freeze the 6502 CPU and steal cycles in order to get screen data from screen memory, 
player/ missile data from player/ missile memory, and to look up character set data. 

It even steals cycles to look at the display list so it knows what
type of information to display. The amount of time stolen per scan line can vary.
ANTIC steals a cycle for each byte in memory it must access. This DMA is controlled
by a hardware register called DMACTL at $D400 (54272 decimal). 

The OS VBlank routine rewrites the value found at its SHADOW (SDMCTL) at $22F (559 decimal)
every VBI. By setting bits in SDMCTL, the program can control screen width from
either 128, 160, or 228 color clocks. Selecting screen width tells ANTIC it may steal
cycles from the 6502 to access the display list and screen memory in order to display
information. Bits are also set here so that ANTIC may steal cycles to look up player
and/ or missile data in memory.